/**
 * Stack - A LIFO (Last-in First-out) Queue, or Stack
 *
 * @author Chris Pratt
 *
 * 1/24/2006
 */
package com.anodyzed.onyx.util;

public interface Stack<E> extends Iterable<E> {

  /**
   * Add an Element to the Top of the Stack
   *
   * @param e The Element to Push onto the Stack
   * @return true if successful
   */
  public boolean push(E e);

  /**
   * Retrieve the Top Element on the Stack without modifying the Stack
   *
   * @return The Top Element on the Stack
   */
  public E peek();

  /**
   * Retrieve the Element <code>n</code> from the Top without modifying the
   *  Stack
   *
   * @param n The distance from the top of the stack to peek
   * @return The <code>n</code><small>th</small> Element from the Top of the Stack
   */
  public E peek(int n);

  /**
   * Retrieve and Remove the Top Element from the Stack
   *
   * @return The Top Element on the Stack
   */
  public E pop();

  /**
   * Remove all the Elements from the Stack
   */
  public void clear();

  /**
   * Test whether the stack is empty
   *
   * @return true if there are no elements in the stack
   */
  public boolean isEmpty();

  /**
   * Return the number of elements on the Stack
   *
   * @return element count
   */
  public int size();

} //#Stack
